Documentation Mailing Lists FAQ Frequently Asked Questions v2

Topic: Views

The output generated by AA is controlled by aliases. The aliases are 10 letters long words defined on 'Admin' -> 'Fields' -> 'Edit' page. Aliases are obviously expanded to the content of some database field or its modification (like How to use aliases alias). For modification of behavior of the alias we use alias functions, as described on
http://apc-aa.sourceforge.net/faq/#216.
http://apc-aa.sourceforge.net/faq/#291.

Since the AA version 2.1 there is possibility to use the aliases NESTED, which means that you can use another alias in the alias definition. For example this Parameters to f_c alias functions are possible:

!:<img src=":" _#PHOTO_WI _#PHOTO_HE alt="photo">::

which displays image (if it is defined). The aliases _#PHOTO_WI _#PHOTO_HE must be defined, of course.

You can use there not only the aliases, but it is possible to use any of database field directly there. Imagine, we store type of record in switch.........1 field (for example text/audio/video). If we create three images - icon_text.gif, icon_audio.gif, icon_video.gif, we can add an icon before each link by the following Parameters to f_m alias function:

<img src="img/icon_{switch.........1}.gif" width="14"> :text...........1::href:class="green10"

The AA version 2.2-pre (04/25/2002) give you new possibilities in alias definition - IN-LINE ALIAS DEFINITION. The parsing of format strings was rewritten, so now you can define aliases not only on 'Admin' -> 'Fields' -> 'Edit' page, but you can define it directly inside the format string (= 'Fulltext HTML code' on 'Design' -> 'Fulltext' page, for example). The new features are 100% backward compatible.

The alias definitions are surrounded by curly braces. There are the possibilities:

1. direct display of some field
   
   ... there is displayed headline: {headline........} <br> Source: ...
   
   
2. constant display
   
   Constants are stored in database as values, but it is possible to convert value back to name, description, ...
   The syntax is : {const_name:category.......1}, {const_description:category.......1}, which displays name (description) of constant stored in field category.......1.
   You can grab following information for the constants:
   

   const_short_id	short_id
   const_name	name
   const_value	value (the same as {category.......1} )
   const_pri	priority number
   const_group	name of constant group
   const_class	class (APC parent category)
   const_id	long constant id
   const_description	description (defined on hierarchy editor pages)

   
   
   
3. display of multivalue fields
   
   ... fields in AA could contain multiple values (categories, ...). It is possible to diesplay it: The example is directly in Item Manager of 'Test News' slice. The syntax is:

   {@category.......1}	displays list of 'values' - comma separated (comma is default)
   {@category.......1:-}	displays list of 'values' - dash separated (it is usefull for example in display of related items: {view.php3?vid=11&cmd[11]=x-11-{@relation.......1:-}}
   {@category.......1:,:<b>_#1</b>}	displays list of 'values' in bold - comma separated (_#1 is alias for the values)
   {@category.......1:,:<a href="/category.shtm?conds[0][category.......1]=_#1">_#1</a>}	displays list of categories with link to the each category
   {@category.......1(const_name,const_value,const_short_id):,:<a href="/category.shtm?conds[0][category.......1]=_#2">_#3 _#1</a>}	displays list of categories with link to the each category, but the text shows category name (and short_id) instead of value. You can use as many constant translations as you want in the parethes. See 'constant display' for list of possible values in previous paragraph.

   
   
   
4. direct display of a variable defined with als or in $apc_state:
   
   ...view.php3?vid=123&als[heading]=My Page

and then ... <h1>{heading}</h1>
   
   The same syntax will find variables defined in apc_state (by the site module).
   
   
5. modification through alias functions:
   

   ... The previous example is good, but sometimes we need to modify the database field before it is displayed. For example the date field is displayed as number if seconds since begin of year 1970, which is probably not exactly what we want to show to user. The solution is to use alias function modification, which has the following syntax:
   
   alias:<the field>:<alias function>:<parameters>
   
   So, in text (format string) could be the publish date displayed by {alias:publish_date....:f_d:j.n.Y}. There you can use any alias function with any parameters.

   The parameters could be nested, so inside curly braces you can use any alias (How to use aliases), any other field ({headline........}) or any other in-line alias definition. There is no limit in level of nesting.

   For example, conditional display of date could look:
   
   {alias:switch.........1:f_c:text:{alias:publish_date....:f_d:j.n.Y}<!--:-->::}
   
   or if we have 06/19/2002 alias defined:
   
   {alias:switch.........1:f_c:text:06/19/2002<!--:-->::}
   

   Both this constructs displays date only if switch.........1 is equal to 'text'. ...

6. comments
   

   ... as addition to in-line aliases you can {# make comments} which is not displayed in result html code. It could be nested again, so you can {# comment out _#ALIASES_ as well as fields {headline........} or alias definitions } - nothing will be in result HTML code ...

7. switch
   

   ... the really new and very useful construct is switch. Many of us knows the troubles with conditional expressions, managed so far by f_c function. Now there is much better solution, which allows more options, regular expressions, ... The syntax is:
   
   {switch(<condition>)<option1>:<output1>:<option2>:<output2>:...[:<default_output>]}
   
   which we can explain on example:
   
   {switch({number.........1})1:one:2:two:[3-7]:more:too much}.
   

   This construct evaluates the condition, which is the content of the number.........1 field in our case. If content of the field is equal to 1, the 'one' is printed. Because 'options' are regular expression, we can specify the third option as [3-7] which means any number in range between 2 and 7. The default option is 'too much' in our case. The evaluation of options goes from left to right and the output is printed only for the first matching option.

   The 'switch' could be used instead of f_c alias function in many cases:
   
   {switch({switch.........1})text:06/19/2002}
   
   This expression could replace the expression in the paragraph 2)
   

   Another example displays text 'Continuos grant', if the field unspecified....2 is filled by 'yes', 'on', 'true' or '1'. Else it displays expiry date:
   
   {switch({unspecified....2})yes|on|true|1:Continuos grant::12/11/2007}
   

   Display of phone number, if specified (as obvious, '#:' stands for ':' if you do not want to use it as argument separator:
   
   {switch({con_phone......1}).+:Tel#:{con_phone......1}}
   

   Last example demonstrates the fact, that there is no limit in <condition>. There could be not only field (in curly braces), but there could be also any alias, alias definition or its combination. The level of nesting of 'curly braces expressions' is again unlimited.
   
   {switch({1})[1-9][0-9]*:There is discussion under this item}
   

8. Inclusion of a view
   {view.php3?vid=123}

   Returns content of view 123. View uses the just like the view.php3 script, and can nest other {} structures. (e.g. {view.php3?vid=122&cmd[122]=c-1-{f}} ) Very useful for displaying related items e.g. {view.php3?vid=33&cmd[33]=x-33-{relation.......1}}

9. includes (added 06/20/2002 - will be in AA v2.2.1)
   

   ... Sometimes we need to include some file or output of some script into the page. Now, there is {include(<file>)}, which will be replaced by the file. The file is called through HTTP request. No matter if included file is html, shtml, php, ...:
   
   the page was visited {include(cgi/counter.pl?id=222)}
   
   (the result of http://www.example.com/cgi/counter.pl?id=222 will be printed)
   
   APC news: {include(http://apc.org/apps/aa/view.php3?vid=112)}
   
   (the remote view (from APC site) will be printed)
   
   If you want to include other slices, it could be usefull to pass the URL parameters to the included file. In this case use the special URL_PARAMETERS constant:
   
   {include(fulltext.shtml?URL_PARAMETERS)}
   
   The limits:

   • It runs only on http:// sites (https:// is not supported until PHP v4.3.0 will be released)
   • There is also limited size of included file. The default limit is 400kB, but you can change it by INCLUDE_FILE_MAX_SIZE constant in config.php3.
   • Also you should know, that each include generates one more HTTP request to server. That's why also the performance is not as big as for the other alias types.
   This can be used in an alternative syntax {include:<file>} or {include:<file>:http} which work exactly the same or {include:<file>:fileman} which will try and read the file directly from the Fileman directory for the slice being used. (this code is new 23 may 2003 and the definition of which slice is being used might change)

10. mathematics operations (new in AA v2.4.0)
    

    ... If you want to compute some walue from datadase field, use the {math..} alias. The syntax is ...:
    
    {math(result_formatting) description1: expression 1: description2: expression2:...:description x : expression x }
    
    where:
    

    result_formatting	has 3 parameters separated by '#' (number of decimals # decimals separator # thousands separator)
    description	can be any text or html and is displayed before result of expression ("#:" mean ":")
    expression	in expression can be used numbers (decimal separator is ".". Aliases can be used of course) and characters: + - / * ^ . ( )

    
    example 1 - use in inquiry
    

    
    <img src="red.gif"   height=10 width="{math(0#,#) : {_#ANSVER1_} / ({_#ANSVER1_} + {_#ANSVER2_} + {_#ANSVER3_})* 100}%">  _#ANSVER1_ <br>
    <img src="blue.gif"  height=10 width="{math(0#,#) : {_#ANSVER2_} / ({_#ANSVER1_} + {_#ANSVER2_} + {_#ANSVER3_})* 100}%">  _#ANSVER2_ <br>
    <img src="green.gif" height=10 width="{math(0#,#) : {_#ANSVER3_} / ({_#ANSVER1_} + {_#ANSVER2_} + {_#ANSVER3_})* 100}%">  _#ANSVER3_ <br>
    
    
    if _#ANSVER1 = 25, _#ANSVER2 = 50, _#ANSVER3 = 250 result will be:
    
    
    <img src="red.gif" height=10 width="8%">  25   <br>
    <img src="blue.gif" height=10 width="15%">  50   <br>
    <img src="green.gif" height=10 width="77%">  250   <br>
    
    

    
    example 2 - cost of ordered services last year
    

    
    {math(2#,# ) <br>mails=:{_#NOOFEMAI}*{_#EMAPRICE}:
                 <br>web=:{_#WWWPRICE}:
                 <br>technical support=:{_#NOOFHOUR}*{_#HOURPRIC}:
    <br><hr>total={_#NOOFEMAI}*{_#EMAPRICE}+{_#WWWPRICE}+{_#NOOFHOUR}*{_#HOURPRIC}
    }
    
    
    result:
    
    mails=450,00
    web=1500,00
    technical support=2400,00
    ----------------------------
    total=4350,00
    

11. user informations (new in AA v2.6 (CVS 05/19/2003))
    

    In AA v2.6 is new Reader Management, where you can control access to directory or file through AA admin interface (see Reader Management). You can then display informations about logged user by {user:} construct.
    The syntax is following:
    

    {user:}	displays login of current user (this option do not search in database, so it is quick) You can use this parameter even if you do not use Reader Management slice and you are using standard Apache's password file auth ...
    {user:password}	displays password of current user (in plain text) (this option also do not looks into database, but into internal server variable, so it is also quick)
    {user:headline........}	displays headline........ field for current user, which is grabbed from Reader Management slice. There is no need to specify in which Reader Management slice user is, because all users are unique in all Reader Management slices. If the Reader Management slice is protected by password (see 'Slice Admin' -> 'Slice' -> 'Password for Reading'), you have to add slice_pwd parameter to view.php3 (or slice.php3), in which you want to display user's database info. You can of course display any field from Reader Management slice.
    {user:role}	displays user's permission role (author/editor/administrator/super/undefined) (usefull in AA admin interface when you want to display another informations to authors and editors - use it in switch() - like {switch({user:role})editor:_#POSTED_BY} )

    Such construct you can use in any view or slice - just like any other aliases.

12. page scroller (for site module only)
    

    ... If you want to use page scroller (Page 1 | 2 | 3 | ... ) in view , which is part of 'site'! (see site module), the {scroller} syntax construct is the right tool. You just add {scorller} to the view, there you want to usepage scroller - probably in the 'Bottom HTML' fileld of the view:
    
    {scroller:Page ::class="blue"}
    
    The syntax for {scroller} is:
    
    
    {scroller:begin:end:add:nopage}
    
    where:
    

    begin	text to be shown before page numbers
    end	text to be shown after page numbers
    add	option to be added to page number <a href=".." class="blue10v">1</a>
    nopage	text to be shown wnen there are (yet) no pages (so the scroller is not displayed)

    Then you use quite normal view include using {p} state variable, which stores the page number in the site module's spot:
    
    {view.php3?vid=32&set[]=page-{p},listlen-10}

13. Debugging

    Because it is sometimes unclear which substitutions are available at a certain point, {debug} will output some hopefully useful information

In this example, we are trying to only show alias for page numbers (_#NM_PAGES) when it is greater than zero.

The field input has Validate: Number, so it generates a zero when left blank. To not show the alias and label when zero, use:

{switch({_#NM_PAGES})^0:: _#NM_PAGES pages }

This switch will show nothing when the number starts with 0, otherwise it will show e.g. "15 pages". Since number validation removes preceeding zeros e.g. 0020, this should always work.

Expired items are normaly not visible on the public website. However is it usefull to sometimes show expired items such as for archives.

There are two easy steps to show expired items in a view:

1. Make sure display of expired items is permitted by setting ALLOW_DISPLAY_EXPIRED_ITEMS constant to true in config.php3
   
2. Define a condition where 'expiry_date.....' is specified. You can use a condition fields in a view design or a search condition or a condition in an URL or SSi using cmd[]-c or cmd[]-d see parameters to view.php3

Example of condition fields in a view design:

set Condition 1 'expirary date' < 9999999999999
(this is a unix date in far far far future - you'll be dead :^)

Example of view.php3 parameter:
.../view.php3?vid=23&cmd[23]=d-expiry_date.....-e:>-1.1.1998

This example uses 1 view, 3 categories, and 2 levels of constants. The catgories are not important but maybe you like to use them so I left them in there.

The view below manages a two level side bar menu. It highlights the branch you are in and the (sub)item you have selected. Example can be seen here http://pi.gn.apc.org

The constants are used as the menu entries. You have to use hierarchical constants and define the constants like this:

Level 0: Name      Value 
         Terrorism Terrorism 
         Policy    Policy ... 

Level 1: Name                        Value
         Politics of Terrorism       Terrorism::Politics of Terrorism Defining 
         Terrorism and Emergencies   Terrorism::Terrorism and Emergencies 
         IGOs and Laundering Policy  Policy::IGOs and Laundering Policy
         ... 

Now create a new constants view Paste the text below into Odd Rows.  Set the Group by to "Value Select" the hierarchical constant group created above View 342 is the listing view I use to display items from my slice.

The slice has 3 categories. This menu only manages the selection of the first category (category........) which is set to use the constant group created above. Further it's first confition is set to LIKE (name of category........). You will have to replace 342 in the text below with your listing view. You can leave away most of the {country}-stuff. To work this just needs {theme} and {_parent_}.

TODO: use better names for the aliases. 'theme' and 'country' might be substrings in the constants. That would cause havoc! All left to do now is to create your style sheet. Have fun!

----------SNIP SNIP----------

{switch({_#LEVEL##_})0:<br>
  {switch({theme}).*theme.*:
    <div class="constView_ContentThemes_ListEntry">
  :{_#NAME###_}.*:
    <div class="constView_ContentThemes_ListEntry_Hl">
    :<div class="constView_ContentThemes_ListEntry{switch({_parent_}){_#NAME###_}.*:_Hl}">
  }
  <a href="/index.shtml?cmd[342][]=c-1-{_#NAME###_}&als[theme]={_#NAME###_}&conds[1][category........]={_#NAME###_}{switch({_#VALUE##_}){theme}.*:&als[_parent_]={theme}}{switch({country}).*country.*::&cmd[342][]=c-3-{country}&als[country]={country}&conds[3][category.......2]={country}}" class="constView_ContentThemes_ListEntry_link">_#NAME###_</a>
  </div>
:1:<!--{theme}--_#VALUE##_--_#NAME###_-->
  {switch({_parent_}).*_parent_.*:
    {switch({theme}).*theme.*::
      {switch({_#VALUE##_}){theme}.*:<div class="constView_ContentThemes_SubListEntry{switch({theme}){_#NAME###_}.*:_Hl}"><a href="/index.shtml?cmd[342][]=c-1-{_#NAME###_}&als[theme]={_#NAME###_}&conds[1][category........]={_#NAME###_}&als[_parent_]={theme}{switch({country}).*country.*::&cmd[342][]=c-3-{country}&als[country]={country}&conds[3][category.......2]={country}}" class="constView_ContentThemes_SubListEntry_link">{_#NAME###_}</a></div>}
    }
  :{switch({theme}).*theme.*::
    {switch({_#VALUE##_}){_parent_}.*:<div class="constView_ContentThemes_SubListEntry{switch({theme}){_#NAME###_}.*:_Hl}"><a href="/index.shtml?cmd[342][]=c-1-{_#NAME###_}&als[theme]={_#NAME###_}&conds[1][category........]={_#NAME###_}&als[_parent_]={_parent_}{switch({country}).*country.*::&cmd[342][]=c-3-{country}&als[country]={country}&conds[3][category.......2]={country}}" class="constView_ContentThemes_SubListEntry_link">{_#NAME###_}</a></div>}
    }
  }
}

----------SNIP SNIP----------

• nothing - standard "no item found" message is displayed (this setting is historical)
• any text - the text is displayed. From AA v2.6 you can also use aliases and other AA expressions like {switch()...}...
• <--Vacuum--> - if you use this keyword (exactly!), nothing is displayed.

One recomendation is to write something that relates to the slice content, e.g. "No news found" or "No events found", with in visible HTML or a comment tag. This helps with both usability and view development problem solving.

This can be done thanks to function f_y - expanded string.

1. In the slice "Photogallery" make a view or views, which will show a single photograph.
2. It is usefull to define the aliases in the Slice Admin / Design / Item Manager, so in the Item Manager you will see below any photograph the alias or aliases for showing it, e.g.: "{view.php3?vid=1047&cmd[1047]=i-1047-6341bce1bd2d5072f75cc440d6e1edf4}"
3. In the slice "Articles", for the field "full_text......." create an alias e.g. _#FULLTEXT with fuction "f_y" and with no defined parameters.
4. During the editing of items you can just copy the aliases from the slice "photograph" to the places in the text, where you would like to have the photographs

See an example.

(was on http://mimo.gn.apc.org/mlx)

The Item Listing View (View.php3) and Design-Index (slice.php3) provide overlapping features. Which to use will depend on which features you need. Here are some of the differences.

Views are useful when you want functionality a little bit different from the standard Index, or Full-Text views. You can use them to customize sorting, or pick certain items or only a subset of the items.

You have to be the slice administrator, then from the standard admin page select Admin -> Views, then you select "Item Listing" and click New.

The first few items are the same as for creating Index views (see the manual). You can then specify how to sort items, and specify a condition (that can take a parameter in the URL).

<!--#include virtual="/aa/view.php3?vid=5"-->

Will embed view number 5 into your page. The view knows which slice it applies to, so this can be embedded in an Index or Full Text View.

View.php3 will take parameters either in the "include" line, or in the URL of the page to which it refers.

You can sort items by specifying in the definition of the view (Admin->Views then select an existing View or click New) which fields to sort by, and wether to sort ascending or descending. The primary sort is the main ordering, and the secondary sorts within this. So for example you might specify Category as the primary sort, and sub-category as the secondary. Note that if you sort on a field then there is a bug (or feature) where items without that field defined will not show up in the index view.

Because views do not currently use sessions. There is no way, how to add 'Previous 1 2 .. Next' scroller to the 'view'.

This is the biggest limitation of 'Views' and we have to count with it.

To select just a sub-set of the items, specify a Condition, or set of conditions, you can then parameterise that in the include statement or URL. So for example, if you set Condition 1 to "Category" and "LIKE" then you can specify a parameter of "cmd[5]=c-1-News" to set the first condition on View 5 to "News" so that it would list any item with a category containing the string "News". This condition could be set in either the Include statement or the URL e.g.

<!--#include virtual="/aa/view.php3?vid=5&cmd[5]=c-1-News"-->

or in the URL.

?cmd[5]=c-1-News&.....

If there are special characters in the search term, i.e. dashes (as in E-mail) or spaces then quote it, and escape the quotes, for example to select a category=Social Ecology would require a URL of the form:

conds[0][category........]=%22Social%20Ecology%22

(%22 is a double quote (") and %20 is space). If you are constructing this URL from somewhere else and do not know what could be in the field then make sure to quote and urlencode the string.

Create a Full-Text view by going to Admin->Views and selecting "Full Text" and clicking "New". Then you can specify cmd[5]=i-5-1a2b3c4d in the URL or include statement. You can also use cmd[5]=x-5-934 where 934 is short _id

The right alias is _#ITEM_ID#.

For example, to show an item in a full text view, the view.php3 script should get the parameters like:

vid=110&cmd[110]=i-110-2548e4b7ae7b8874ee4a4bf

( the 'i' command to view.php3 script takes as argument unpacked (long) item id)

So if we pass the vid parameter directly in fulltext.shtml page:
fulltext.shtml:

<!--#include virtual="/aaa/view.php3?vid=110"-->

Which then needs us to pass the cmd parameter through url:

<a href="fulltext.shtml?cmd[110]=i-110-2548e4b7ae7b8874ee4a4bf"> fulltext </a>

So we can generate this by placing in the Odd rows field of an index view

<a href="fulltext.shtml?cmd[110]=i-110-_#ITEM_ID#"> fulltext </a>

If you want to link to a view appearing in the same place on the same page (as for the main index going to a full text), then if your Index view has vid=109 then the URL should be:

"?cmd[109]=i-110-_#ITEM_ID#"

which will redraw the same screen, replacing view 109 with view110, for the item specified.

Static Views are a bit like macros, they are not related to a specific item or slice, but can be used where the same content, or parameterised content is needed on many pages.

It is a view that only has one format - the 'Odd Row' format. It does not lookup the values for any items or fields, but just prints the 'Odd Row format'.

However they can take parameters from the URL

You can use aliases defined in the URL parameter 'als'. For a detailed description of the als parameter, see "What parameters can I use with slice.php3"

For example,

There are 13 navigation pages. For example, there is a page on 'Communication Rights' which has a report on Internet Rights in general and links to the pages
'Communication Rights in South Africa'
'Communication Rights in Morocco'
'Communication Rights in Senegal'
etc...

I did not want to write 13 pages, so I used 2 static views -- one for country pages, and one for topic pages.

The topic page is /topic.shtml. It has this include

<!--#include virtual="/apc-aa/view.php3?vid=2-->

topic.shtml will be called with parameters. To create the 'Communication Rights' topic page, it will be called as

/topic.shtml?als[MY_TOPIC]=Communication+Rights&als[URLE_TOP]=Communication%2BRights

URLE_TOP is an alias similar to MY_TOPIC, but it double URL encodes the value. It will be used to generate links. %2B represents the +. A + in url encoding is a space.

In this topic.shtml I want to create links to these pages. To create these links, view #2 has this 'odd row' format:

<a href="/resource.shtml?cmd[1]=c-1-South%2BAfrica-c-2-_#URLE_TOP">South Africa - _#MY_TOPIC </a>
<a href="/resource.shtml?cmd[1]=c-1-Morocco-c-2-_#URLE_TOP">Morocco - _#MY_TOPIC </a>
<a href="/resource.shtml?cmd[1]=c-1-Senegal-c-2-_#URLE_TOP">Senegal - _#MY_TOPIC </a>

and the MY_TOPIC and URLE_TOP are substituted from the als parameters in the URL.

Views can be swapped in and out from the URL, using syntax like "cmd[5]=v-8" to display view 8 at the place where View 5 was expected (for example by <!--#include="/aa/view.php3?vid=5"-->

For example, if you want a navigation menu that redraws itself depending on what is clicked on, you should create each of the different views you want to appear and then include one view in the shtml page. Then you can switch between displayed views using the url parameter.

For Example:
----------- index.shtml ----------
[...]
<h3>content</h3>
<!--#include virtual="/apc-aa/view.php3?vid=9"-->
<p> page footer... </p>
[...]

--------- code for this menu in the Odd row field of view #9-----
[...]
<a href="index.shtml?cmd[9]=v-13">News</a><br>
<a href="index.shtml?cmd[9]=v-14">Calendar</a><br>
<a href="index.shtml?cmd[9]=v-15">About us</a><br>
[...]

When the index.shtml page is redrawn the initial view #9 will be replaced by the appropriate view, for example view #13 will appear in the News slice and view #14 in the Calendar slice.

Because the PHP is interpreted via an include on the server, you cannot easily change the view at run-time, for example changing it based on a mouse-over event, it requires a page to be redrawn.

Javascript item exchange View is a type of View. It works exactly the same as a standard view, but the primary usage for this type is to show items on any page around the Internet. For a simpler way of doing this, see "How do I use jsview.php3 to view pages on a site where AA is not installed."

The destination page should contain a HTML tag like:

<SCRIPT LANGUAGE= "JavaScript"SRC="http://aa.ecn.cz/apc-aa/view.php3?vid=1"></SCRIPT>

This tag includes the output of view to any page on Internet (there is no restriction to one server).

Because such tag requires javascript as output of view.php3, the format strings for the view (Admin -> View) should look like:

Note that there is (or was) a bug where if the item would generate no items then you'll get an error rather than empty Javascript.

The only required parameter to view.php3 script is number of view to show. This parameter is given by vid url variable. All remaining parameters are optional.

Each optional view parameter begins with cmd[x], where x is view number in which the parameter should be used. This is needed because of possibility to include more than view to one shtml page. That's why we need to specify, for which view the command should work.

It is impossible to specify more than one cmd for one view. If you want to use cmd[]=d for the view, you can't use it with combination with cmd[]=c, for example.

Above is still true, even after CVS snapshot 20031109, since when you can also use this syntax: vid=x&cmd[x][]=c-1-<something>&cmd[x][]=c-2-<something>. Note the extra [].

However, you can use more settings (set[x]) per view. Just seperate settings with a comma, like: set[23]=from-10,to-20.

After the cmd[x]= is always character, which specify which command is used - how modify the view. The c command modifies conditions, for example. The values after command character are user parameters and its meaning is different for each command. The parameters are separated by '-' character. If you need to use a hyphen '-' in a parameter, use 2 hyphens '--' instead. Description of parameters is in following table of examples.

If you want to display some view on page, which is stored on site where is not installed AAs, you have three possibilities.

1. use remote, remotec or remotec.php
2. create javascript view - this is good if you want to do something complex with the Javascript.
3. use the jsview.php3 to display existing view.
   

This answer covers point 3) - jsview.php3

The usage is easy. Just replace SSI include in original shtml age with the javascript one. The jsview.php3 takes exactly the same parameters as view.php3.

For example, if the old SSI code in page.shtml was:

<!--#include virtual="/apps/aa/view.php3?&vid=2&cmd[2]=c-1-APC" -->

the new javascript code in page.shtml would be:

<script type="text/javascript" src="http://www.apc.org/apps/aa/jsview.php3?vid=2&cmd[2]=c-1-APC"></script>

Normally you will want either a Item listing, Full text or Static Page view.

• Item Listing - these are used like the main Index view to generate a list of some or all the items in a slice.
• Fulltext View - these are used to display a single item.
• Item Digest - not sure what these are.
• Discussion - used for creating discussions
• View of Constants - used to display list of constants (ie. categories).
• RSS Exchange - used to exchange items with Content Management Systems that use this standard
• Static Page - these are a bit like macros, they are not related to a specific item or slice, but can be used where the same content, or parameterised content is needed on many pages.
• Javascript item exchange - used to view items on a site without AA installed.
• URL Listing - special view used mainly for creating list of links to all articles in the slice, which is used for search robots and fulltext indexers like Google, HtDig or MnoGoSearch. It is very similar to Item Listing, but you can use just very limited set of fields and aliases, so there is no problem with "memory limit".
• Calendar view is a complex view used for showing event items within a monthly calendar.

• Link listing and Category listing views are used for Links module - you can customize the design of links listing and category listing just like jot normal AA items. The usage is analogous to Item listing and is quite simple, but deep documentation of those views wait for someone, who will have resources to document Links module.

The slice.php3 is the main script used to display items from database. The alternative for this script is view.php3. The main ussage of slice.php3 script is to include it into some .shtml file by the SSI include command - like:

 <!--#includevirtual="/aaa/slice.php3?slice_id=a91256ed53287912d74495d781076bd6"-->

<!--#includevirtual="/aaa/slice.php3?slice_id=a91256ed53287912d74495d781076bd6&listlen=10&no_scr=1"-->

The slice.php3 is there from the beginning of ActionApps, so some of the parameters are quite old. Such parameters are still implemented, but in many cases it is better to use newer - more powerfull substitution for the parametr. That's why the list is prioritized from the most common parameters (which should be used) to the old parameters (which use is deprecated).

1. unalias (expand) whole text (replace aliases and any other AA expressions)
2. remove all specified remove strings

Removing of stings works before alias substitution - it never replaces the text filled by user in the field. If you have

=> _#HEADLINE (_#AUTHOR##)

and remove string "()", than it first looks for empty alias content and then removes such aliases.

Let _#HEADLINE = "Hi Ann"
and _#AUTHOR## = "" (empty)

In first step the emtpty aliases are removed:

=> _#HEADLINE ()

Then the "remove strings" are removed:

=> _#HEADLINE

and then the remaining aliases are substituted.

With the concept of Reader management slices introduced it is important that some data are not accessible for reading. This is achieved by setting a reading password for slices containing sensitive data. If you fill the field "Reading Password" in Slice Settings, you must always sent this password as a parameter slice_pwd. This may be done by adding this parameter to SSI includes like

<!--#include virtual="/aa/slice.php3?slice_pwd=the_password&slice_id=xy...."-->

If somebody tries to fetch read-protected data without the correct password, all fields are filled with an error message.

If you are interested, the password is prooved in the GetItemContent() function. For AA control panel pages (Item Manager and Item Edit), the function FetchSliceReadingPassword() is used.

• _#this is replaced by the content of the field we are working on, typically this is the long id of the item being referenced. If there are multiple id's they are strung together seperated by "-" which is what view.php3 expects in its parameters.
• _#slice is replaced by the slice id.
• _#unpacked_id is replaced by the id of the record as output by f_n.
• _#id.............. will get the id of the record, (unclear if this is unpacked or packed)
• _#short_id........ will get the short id of the record
• _#slice gets the id (unclear if packed or unpacked) of the slice
• _#headline........ (or any other field) will get that field, or a list of them separated by "-"
• In addition any of the { ... } syntax can be used, (See How to Use Aliases)

This FAQ interface was developed by Jason at Commons.ca

APC ActionApps is a free software content management system initiated by the Association for Progressive Communications (APC) APC - Internet and ICTs for social justice and development